---
sidebar_label: Actions
sidebar_position: 15
description: Manage Actions with the Hasura schema/Metadata API
keywords:
  - hasura
  - docs
  - schema/Metadata API
  - API reference
  - actions
---

# Schema/Metadata API Reference: Actions (Deprecated)

:::caution Deprecation

In versions `v2.0.0` and above, the schema/Metadata API is deprecated in
favour of the [schema API](/api-reference/schema-api/index.mdx) and the
[Metadata API](/api-reference/metadata-api/index.mdx).

Though for backwards compatibility, the schema/Metadata APIs will
continue to function.

:::

## Introduction

**actions** are user defined mutations with custom business logic.

## create_action {#schema-metadata-create-action}

`create_action` is used to define an action. There shouldn't be an
existing action with the same name.

Create a synchronous action with name `create_user`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"create_action",
   "args":{
      "name":"create_user",
      "definition":{
         "kind":"synchronous",
         "arguments":[
            {
               "name":"username",
               "type":"String!"
            },
            {
               "name":"email",
               "type":"String!"
            }
         ],
         "output_type":"User",
         "handler":"https://action.my_app.com/create-user",
         "timeout":60
      },
      "comment": "Custom action to create user"
   }
}
```

### Args syntax {#schema-metadata-create-action-syntax}

| Key        | Required | Schema                                                              | Description              |
| ---------- | -------- | ------------------------------------------------------------------- | ------------------------ |
| name       | true     | [ActionName](/api-reference/syntax-defs.mdx#actionname)             | Name of the action       |
| definition | true     | [ActionDefinition](/api-reference/syntax-defs.mdx#actiondefinition) | Definition of the action |
| comment    | false    | text                                                                | comment                  |

## drop_action {#schema-metadata-drop-action}

`drop_action` is used to remove an action. Permissions defined on the
Actions are also dropped automatically.

Drop an action `create_user`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"drop_action",
   "args":{
      "name":"create_user",
      "clear_data": true
   }
}
```

### Args syntax {#schema-metadata-drop-action-syntax}

| Key        | Required | Schema                                                  | Description                                                                                                 |
| ---------- | -------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| name       | true     | [ActionName](/api-reference/syntax-defs.mdx#actionname) | Name of the action                                                                                          |
| clear_data | false    | boolean                                                 | If set to `true` and action kind is `asynchronous`, related data is deleted from catalog. (default: `true`) |

## update_action {#schema-metadata-update-action}

`update_action` is used to update the definition of the action.
Definition thus provided is replaced with existing one.

Update an action `create_user` by making it's kind to `asynchronous`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"update_action",
   "args":{
      "name":"create_user",
      "definition":{
         "kind":"asynchronous",
         "arguments":[
            {
               "name":"username",
               "type":"String!"
            },
            {
               "name":"email",
               "type":"String!"
            }
         ],
         "output_type":"User",
         "handler":"https://action.my_app.com/create-user"
      },
      "comment": "Custom action to create user",
   }
}
```

### Args syntax {#schema-metadata-update-action-syntax}

| Key        | Required | Schema                                                              | Description                             |
| ---------- | -------- | ------------------------------------------------------------------- | --------------------------------------- |
| name       | true     | [ActionName](/api-reference/syntax-defs.mdx#actionname)             | Name of the action                      |
| definition | true     | [ActionDefinition](/api-reference/syntax-defs.mdx#actiondefinition) | Definition of the action to be replaced |
| comment    | false    | text                                                                | comment                                 |

## create_action_permission {#schema-metadata-create-action-permission}

`create_action_permission` is used to define a permission to make action
visible for a role.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "create_action_permission",
  "args": {
    "action": "create_user",
    "role": "user"
  }
}
```

### Args syntax {#schema-metadata-create-action-permission-syntax}

| Key     | Required | Schema                                                  | Description        |
| ------- | -------- | ------------------------------------------------------- | ------------------ |
| action  | true     | [ActionName](/api-reference/syntax-defs.mdx#actionname) | Name of the action |
| role    | true     | [RoleName](/api-reference/syntax-defs.mdx#rolename)     | Name of the role   |
| comment | false    | text                                                    | comment            |

## drop_action_permission {#schema-metadata-drop-action-permission}

`drop_action_permission` is used to drop a permission defined on an action.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "drop_action_permission",
  "args": {
    "action": "create_user",
    "role": "user"
  }
}
```

### Args syntax {#schema-metadata-drop-action-permission-syntax}

| Key  | Required | Schema                                                  | Description        |
| ---- | -------- | ------------------------------------------------------- | ------------------ |
| name | true     | [ActionName](/api-reference/syntax-defs.mdx#actionname) | Name of the action |
| role | true     | [RoleName](/api-reference/syntax-defs.mdx#rolename)     | Name of the role   |
